/********************************************************************
 * PROJECT: FOLIAGE PROJECT.
 * SUPPLIER: FOLIAGE TEAM.
 ********************************************************************
 * FILE: DeepTreeNode.java
 * (C) Copyright Foliage Team 2013, All Rights Reserved.
 ********************************************************************/
package org.foliage.common.structure;

/**
 * 一般有序树结点数据结构，父子表现式，且每个结点均带有唯一标识。定义深度的上下级查询功能功能接口。适用于多层次深度查询。
 * 
 * @author deathknight0718@gmail.com
 * @version 1.0.0
 */
public interface DeepTreeNode extends TreeNode {

	/**
	 * 获取该实例所属树形结构的最大深度值。
	 * 
	 * @return 深度值。
	 */
	int getTreeDepth();

	/**
	 * 获取该实例在所属树形结构中的深度值。
	 * 
	 * @return 深度值。
	 */
	int getTreeNodeDepth();

	/**
	 * 根据指定的相对深度值获取该实例的直系祖先结点实例。
	 * 
	 * @param depth 相对深度值。
	 * @return 直系祖先结点实例。
	 */
	DeepTreeNode getAncestor(int depth);

	/**
	 * 获取该实例的直系始祖结点实例。
	 * 
	 * @return 直系始祖结点实例。
	 */
	DeepTreeNode getFirstAncestor();

	/**
	 * 根据结点唯一标识获取该结点的对应的直系后裔结点实例。
	 * 
	 * @param key 结点唯一标识。
	 * @return 直系后裔结点实例。
	 */
	DeepTreeNode getDescendant(String key);

	/**
	 * 根据指定的相对深度值和子结点序列号获取该实例的后裔结点实例。
	 * 
	 * @param depth 相对深度值。
	 * @param index 子结点序列号。
	 * @return 后裔结点实例。
	 */
	DeepTreeNode getDescendant(int depth, int index);

	/**
	 * 获取该实例的所有直系后裔结点实例数组。
	 * 
	 * @return 直系后裔结点实例数组。
	 */
	DeepTreeNode[] getDescendants();

}
